Base Layouts and Template Inheritance

**Referenced Files in This Document** - [base.njk](file://src/_includes/layouts/base.njk) - [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk) - [knowledge.njk](file://src/_includes/layouts/knowledge.njk) - [index.njk](file://src/index.njk) - [about.njk](file://src/about.njk) - [cases.njk](file://src/cases.njk) - [media-management.njk](file://src/services/media-management.njk) - [code-of-conduct.njk](file://src/legal/code-of-conduct.njk) - [alliance.njk](file://src/alliance.njk) - [alliance-members.njk](file://src/alliance-members.njk) - [alliance-knowledge.njk](file://src/alliance-knowledge.njk) - [getting-started.md](file://src/content/knowledge/getting-started.md) - [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js) - [.eleventy.js](file://.eleventy.js) - [site.json](file://src/_data/site.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains the base layout system and template inheritance patterns used by the Nunjucks-based static site generator in this project. It focuses on how the base.njk layout acts as the master template for most pages, how IAA-specific layouts extend a narrower master for alliance-related pages, and how knowledge base articles reuse a specialized wrapper. You will learn how {% extends %} directives and block overrides work, how data and filters are integrated, and how to maintain consistency across page types while keeping templates DRY.

Project Structure

The layout system is organized under src/_includes/layouts with three primary templates:

  • base.njk: The global master layout for most public and internal pages
  • iaa-base.njk: A minimal master layout tailored for Invest Australia Alliance pages
  • knowledge.njk: A specialized wrapper that extends base.njk and adds knowledge article scaffolding

Pages and content files declare which layout to use via front matter. Collections and transforms enrich content and metadata during build.

graph TB
subgraph "Layouts"
B["base.njk"]
I["iaa-base.njk"]
K["knowledge.njk"]
end
subgraph "Pages"
H["index.njk"]
A["about.njk"]
C["cases.njk"]
S["media-management.njk"]
L["code-of-conduct.njk"]
AL["alliance.njk"]
AM["alliance-members.njk"]
AK["alliance-knowledge.njk"]
end
subgraph "Content"
G["getting-started.md"]
D["knowledge.11tydata.js"]
end
H --> B
A --> B
C --> B
S --> B
L --> B
AL --> I
AM --> I
AK --> B
G --> K
K --> B

Diagram sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [cases.njk](file://src/cases.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-members.njk](file://src/alliance-members.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js)

Section sources

  • [.eleventy.js](file://.eleventy.js)

Core Components

  • Global master layout (base.njk): Provides the HTML skeleton, SEO metadata, navigation, search modal, main content area, and footer. It exposes a single content block for child templates to render page-specific markup.
  • IAA master layout (iaa-base.njk): A leaner shell for alliance-focused pages, with a dedicated navigation and footer tailored to the Invest Australia Alliance brand.
  • Knowledge wrapper (knowledge.njk): Extends base.njk to provide a standardized article header, breadcrumb, metadata, tags, and body container for knowledge base entries.

Key data and helpers:

  • Site-wide metadata is loaded from src/_data/site.json and injected into templates via the site global.
  • Filters and shortcodes (e.g., dateFormat, readingTime, year) are registered in .eleventy.js and used across templates and layouts.

Practical inheritance examples:

  • index.njk, about.njk, cases.njk, media-management.njk, and code-of-conduct.njk all set layout: base.njk in front matter and render page-specific sections.
  • alliance.njk and alliance-members.njk set layout: iaa-base.njk to inherit the IAA shell.
  • alliance-knowledge.njk sets layout: base.njk and relies on knowledge.njk’s wrapper to render article content.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [cases.njk](file://src/cases.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [alliance.njk](file://src/alliance.njk)
  • [alliance-members.njk](file://src/alliance-members.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [site.json](file://src/_data/site.json)
  • [.eleventy.js](file://.eleventy.js)

Architecture Overview

The inheritance chain is straightforward:

  • Child templates declare a layout in front matter.
  • The chosen layout becomes the parent template.
  • Child templates inject content into the parent’s content block.
  • Knowledge articles use a two-tier inheritance: content files use a layout that itself extends the global base.
sequenceDiagram
participant Author as "Author"
participant Page as "Child Template"
participant Parent as "Parent Layout"
participant Wrapper as "Knowledge Wrapper"
Author->>Page : Write front matter with "layout"
Page->>Parent : Render using parent template
Parent-->>Page : Place child content into "content" block
Note over Page,Parent : Standard inheritance
Author->>Page : Content file with "layout : knowledge.njk"
Page->>Wrapper : Render wrapper
Wrapper->>Parent : Extend base.njk
Wrapper-->>Page : Render article scaffolding
Parent-->>Page : Place wrapper content into "content" block
Note over Wrapper,Parent : Two-tier inheritance

Diagram sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [index.njk](file://src/index.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)

Detailed Component Analysis

Base Layout (base.njk)

  • Purpose: Global HTML shell for most pages.
  • Responsibilities:
    • Head: charset, viewport, title, description, canonical, Open Graph, Twitter Card, fonts, styles, JSON-LD for Organization and optional NewsArticle.
    • Body: navigation, search modal, main content placeholder, footer, and scripts.
  • Content injection: Uses a single content block for child templates to render page-specific markup.
  • SEO and accessibility: Includes structured data, meta tags, and semantic markup for navigation and search.

Best practices:

  • Keep head metadata dynamic via front matter variables (title, description, og_image).
  • Use page.url conditions to load page-specific assets (e.g., GSAP ScrollTrigger on non-home pages).
  • Centralize navigation and footer in the base to ensure consistency.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)

IAA Master Layout (iaa-base.njk)

  • Purpose: Minimal shell for Invest Australia Alliance pages.
  • Differences from base.njk:
    • Simplified navigation and footer focused on IAA branding and links.
    • Different body classes and theme defaults.
    • Removes global search modal and certain analytics/SEO blocks.
  • Content injection: Single content block for child templates.

When to use:

  • Pages that belong to the alliance ecosystem but should not inherit the full public site shell.

Section sources

  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)

Knowledge Wrapper (knowledge.njk)

  • Purpose: Standardized scaffolding for knowledge base articles.
  • Responsibilities:
    • Extends base.njk.
    • Adds breadcrumb navigation, title, metadata (date, author, reading time), optional tags, and a prose-formatted content area.
  • Integration:
    • Content files (e.g., getting-started.md) set layout: knowledge.njk in front matter.
    • A content-level data file (knowledge.11tydata.js) sets the layout and permalink behavior for knowledge articles.

Practical example:

  • A knowledge article declares layout: knowledge.njk and renders Markdown content; the wrapper injects the shared header, metadata, and footer.

Section sources

  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js)

Example Pages and Their Inheritance

Public Pages Using base.njk

  • index.njk: Sets layout: base.njk and renders home page content with macros and carousels.
  • about.njk: Sets layout: base.njk and builds a multi-section biography and values presentation.
  • cases.njk: Sets layout: base.njk and displays a grid of case study cards.
  • media-management.njk: Sets layout: base.njk and presents a service detail page with cards and CTA.
  • code-of-conduct.njk: Sets layout: base.njk and renders a document page with structured headings.
flowchart TD
Start(["Child Template"]) --> Declare["Declare layout in front matter"]
Declare --> Resolve["Resolve parent layout"]
Resolve --> Inject["Inject content into parent's content block"]
Inject --> Render["Render final HTML"]

Diagram sources

  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [cases.njk](file://src/cases.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [base.njk](file://src/_includes/layouts/base.njk)

Section sources

  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [cases.njk](file://src/cases.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)

IAA Pages Using iaa-base.njk

  • alliance.njk: Sets layout: iaa-base.njk and renders an editorial page with marquee, grid sections, timeline, and CTA.
  • alliance-members.njk: Sets layout: iaa-base.njk and builds a dashboard and resource listing for alliance members.
sequenceDiagram
participant P as "alliance.njk"
participant I as "iaa-base.njk"
participant B as "base.njk"
P->>I : Render using IAA layout
I-->>P : Place content into "content" block
Note over P,I : IAA pages bypass base.njk for shell

Diagram sources

  • [alliance.njk](file://src/alliance.njk)
  • [alliance-members.njk](file://src/alliance-members.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)

Section sources

  • [alliance.njk](file://src/alliance.njk)
  • [alliance-members.njk](file://src/alliance-members.njk)

Knowledge Base Articles Using Two-Tier Inheritance

  • alliance-knowledge.njk: Sets layout: base.njk and renders a knowledge index with tag filtering.
  • getting-started.md: Declares layout: knowledge.njk and Markdown content; knowledge.njk extends base.njk and wraps the article.
sequenceDiagram
participant MD as "getting-started.md"
participant WN as "knowledge.njk"
participant BN as "base.njk"
MD->>WN : Render using knowledge wrapper
WN->>BN : Extend base.njk
WN-->>MD : Render article scaffolding
BN-->>MD : Place wrapper content into "content" block

Diagram sources

  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [base.njk](file://src/_includes/layouts/base.njk)

Section sources

  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)
  • [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js)

Dependency Analysis

  • Layout resolution: Eleventy resolves layouts from src/_includes/layouts based on front matter declarations.
  • Data binding: site.json supplies global metadata consumed by base.njk (e.g., canonical URL, social, contact info).
  • Filters and shortcodes: .eleventy.js registers helpers (e.g., dateFormat, readingTime, year) used across templates and layouts.
  • Collections: .eleventy.js defines collections (news, cases, newsletters, teamMembers, services, knowledge) used by pages and wrappers.
  • Transforms: An Obsidian-syntax transform converts wiki links and callouts in knowledge content.
graph LR
E[".eleventy.js"] --> F["Filters & Shortcodes"]
E --> C["Collections"]
E --> T["Transforms"]
S["site.json"] --> B["base.njk"]
B --> H["index.njk"]
B --> A["about.njk"]
B --> C["cases.njk"]
B --> Svc["media-management.njk"]
B --> L["code-of-conduct.njk"]
B --> AK["alliance-knowledge.njk"]
K["knowledge.njk"] --> B
G["getting-started.md"] --> K

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [site.json](file://src/_data/site.json)
  • [base.njk](file://src/_includes/layouts/base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [index.njk](file://src/index.njk)
  • [about.njk](file://src/about.njk)
  • [cases.njk](file://src/cases.njk)
  • [media-management.njk](file://src/services/media-management.njk)
  • [code-of-conduct.njk](file://src/legal/code-of-conduct.njk)
  • [alliance-knowledge.njk](file://src/alliance-knowledge.njk)
  • [getting-started.md](file://src/content/knowledge/getting-started.md)

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [site.json](file://src/_data/site.json)

Performance Considerations

  • Asset loading: base.njk conditionally loads ScrollTrigger and Three.js only when appropriate to reduce payload on non-home pages.
  • Minification: In production, HTML is minified via a transform to reduce bundle size.
  • Efficient collections: Collections are filtered and sorted server-side to avoid heavy client-side computation.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Missing layout: If a page does not declare a layout, it will not inherit any shell. Ensure front matter includes layout: base.njk or layout: iaa-base.njk as appropriate.
  • Incorrect inheritance chain: For knowledge articles, confirm the content file declares layout: knowledge.njk and that knowledge.11tydata.js sets layout: knowledge.njk and permalink behavior.
  • Metadata not rendering: Verify site.json exists and contains required fields; check that base.njk references site globals for title, description, and canonical URL.
  • Search modal not working: Confirm the search modal markup exists in base.njk and that related JavaScript is included.
  • IAA-specific styles not applied: Ensure alliance pages use iaa-base.njk and that IAA-specific CSS is loaded by that layout.

Section sources

  • [base.njk](file://src/_includes/layouts/base.njk)
  • [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk)
  • [knowledge.njk](file://src/_includes/layouts/knowledge.njk)
  • [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js)
  • [site.json](file://src/_data/site.json)

Conclusion

The project’s Nunjucks layout system centers on a robust base.njk that provides global structure and SEO, complemented by a streamlined iaa-base.njk for alliance pages. Knowledge articles benefit from a two-tier inheritance model that keeps article scaffolding consistent while allowing content authors to focus on Markdown. By leveraging front matter, Eleventy’s filters and transforms, and a clear inheritance hierarchy, teams can maintain consistency, improve maintainability, and scale across diverse page types—from public marketing pages to internal knowledge resources.